home *** CD-ROM | disk | FTP | other *** search
/ CICA 1993 April / CICA MS Windows - April 1993.iso / unzipped / programr / toolbar / toolbar.doc < prev    next >
Text File  |  1992-06-26  |  7KB  |  167 lines
  1. DOCUMENTATION ON THE TOOLBAR LIBRARY
  2. ====================================
  3.  
  4. Original work (C) Stephen Chung     (stephenc@cunixf.cc.columbia.edu)
  5. C++ modifications (C) Tim Liddelow     (tim@kimba.catt.citri.edu.au)
  6.  
  7.  
  8. Introduction
  9. ------------
  10.  
  11. This set of routines implement the slick "toolbar" found in Microsoft
  12. Word for Windows, Excel etc.  They are written and compiled using
  13. Borland C++ 2.0 and 3.0.  They should however work fine under other
  14. compilers.  Provided are C routines and a small C++ class.
  15.  
  16.  
  17. How to use
  18. ----------
  19.  
  20. Look at the sample program TBTEST.C for an example.  That toolbar is
  21. part of a Japanese word processor I am writing.  I have not included
  22. the icons because they are embedded in a large .res file with everything
  23. else.  If you want some of them, send me email.
  24.  
  25. First of all, the toolbar is a 3-dimensional, horizontal bar containing
  26. "toolbar buttons".  You can add other kinds of child window controls
  27. onto the toolbar as well, such as combo boxes etc.
  28.  
  29. Before you do anything, you must define an array of TOOLBARICON.  Each
  30. element in that array corresponds to one toolbar button.  The fields
  31. should be set according to the followoing:
  32.  
  33.     int id                  /* The numeric ID of the button (0-255) */
  34.     int x, y                /* The X,Y position of the button, in pixels */
  35.     int width, height       /* The width/height of the button, in pixels */
  36.     int state               /* The initial state of the button:
  37.                                     -1 = Disabled
  38.                                      0 = Off
  39.                                      1 = On
  40.                                      2 = Grayed
  41.                             */
  42.     int cycle               /* The mode of that button, upon a mouse click:
  43.                                      0 = Leave the state alone
  44.                                            (Set it with a BM_SETSTATE message)
  45.                                      1 = Always undepressed, but flashed once
  46.                                      2 = Toggle On --> Off --> On
  47.                                      3 = Toggle On --> Off --> Gray --> On
  48.                             */
  49.  
  50.     char *disabled          /* The name for the DISABLED bitmap */
  51.     char *undepressed       /* The name for the OFF bitmap */
  52.     char *depressed         /* The name for the ON bitmap */
  53.     char *grayed            /* The name for the GRAYED bitmap */
  54.     char *pressing          /* The name for the bitmap for being pressed */
  55.  
  56. You should leave the rest of the fields alone.  They are used internally
  57. by the routines.
  58.  
  59. To create the toolbar, call CreateToolbar.  This routine has the following
  60. parameters:
  61.  
  62.     HWND CreateToolbar (HWND parent, int x, int y, int width, int height,
  63.                         int thickness, int id, int nr_buttons, HANDLE hInstance,
  64.                         TOOLBARICON *icons, char *xcursor)
  65.  
  66.  
  67.     HWND parent             /* The parent window handle */
  68.     int x, y,               /* X,Y position of the toolbar, in pixels */
  69.     int width, height       /* Width and height, in pixels */
  70.     int thickness           /* Its apparant thickness, in pixels */
  71.     int id                  /* ID number */
  72.     int nr_buttons          /* The number of toolbar buttons */
  73.     HANDLE hInstance        /* Instance handle */
  74.     TOOLBARICON *icons      /* Pointer to a TOOLBARICON array */
  75.     char *xcursor           /* The name of the cursor for a disabled toolbar
  76.                                button.  If NULL, the cursor will remain an
  77.                                arrow */
  78.  
  79. The routine will return the handle for the toolbar.  You can use this handle
  80. to add more child controls (see TBTEST.C).
  81.  
  82. The toolbar will send a WM_COMMAND message to its parent when one of its
  83. buttons is clicked.  The following paremeters are passed:
  84.  
  85.         message         WM_COMMAND
  86.  
  87.         wParam          Low Byte =  Toolbar ID
  88.                         High Byte = Toolbar button ID
  89.  
  90.         lParam          Low Word =  Toolbar button window handle
  91.                         High Word = BN_CLICKED
  92.  
  93. REMEMBER that even other child controls that you define (such as list boxes)
  94. will return with wParam = (Child ID << 8) | (Toolbar ID).  This means that
  95. you are restricted to having 256 toolbars and 256 toolbar buttons and child
  96. controls on each toolbar.  Well, life is tough, isn't it?
  97.  
  98. You enable and disable toolbar buttons by calling EnableToolbarButton
  99. with the following parameters:
  100.  
  101.         void EnableToolbarButton (HWND hwnd, int child, BOOL on)
  102.  
  103.         HWND hwnd           /* The window handle of the TOOLBAR */
  104.         int child           /* The ID of the toolbar button */
  105.         BOOL on             /* TRUE = Enable, FALSE = Disable */
  106.  
  107. You can also set or query the state of a toolbar button by sending the
  108. TOOLBAR BUTTON a BM_GETSTATE or BM_SETSTATE message, just as you would for
  109. a normal push button.  You can also send the BM_GETSTATE and BM_SETSTATE
  110. messages to the TOOLBAR, with the toolbar button's ID passed to lParam.
  111.  
  112. If, for some twisted reason, you want to modify the characteristics
  113. of the toolbar button dynamically, you can first call GetToolbarButton
  114. to fill in a TOOLBARICON structure:
  115.  
  116.         HWND GetToolbarButton (HWND hwnd, int child, TOOLBARICON *icon)
  117.  
  118.         HWND hwnd           /* The window handle of the TOOLBAR */
  119.         int child           /* The ID of the toolbar button */
  120.         TOOLBARICON *icon   /* Pointer to a TOOLBARICON structure.  If not
  121.                                NULL, the fields will be filled in with
  122.                                the most current settings. */
  123.  
  124. This routine will return the window handle of the toolbar button.  Now
  125. you can change the settings and then call ModifyToolbarButton:
  126.  
  127.         void ModifyToolbarButton (HWND hwnd, TOOLBARICON *icon)
  128.  
  129.         HWND hwnd           /* The window handle of the TOOLBAR BUTTON! */
  130.         TOOLBARICON *icon   /* The TOOLBARICON structure containing new
  131.                                settings */
  132.  
  133. There is also a neat little routine called Create3DEffect which will
  134. make any rectangle within any window look like a 3-dimensional bar:
  135.  
  136.         void Create3DEffect (HDC hdc, RECT *rect, int thickness)
  137.  
  138.         HDC hdc             /* Device context to draw on */
  139.         RECT *rect          /* Pointer to a RECT structure defining the
  140.                                area to make 3D.  If rect is NULL, then
  141.                                the entire window is 3D'd. */
  142.         int thickness       /* How thick you want the 3D effect to be */
  143.  
  144. If you want to change the name of the toolbar classes, they are defined
  145. in TOOLBAR.H
  146.  
  147. One final thing, you must remember to export ToolbarProc and
  148. ToolbarButtonProc in your .def file of course.
  149.  
  150.  
  151. Afterwords
  152. ----------
  153.  
  154. Theoretically, you are required to obtain special approval from me (because
  155. I copyrighted these routines) if you want to use them in your programs.
  156. However, I usually don't really care if you are not using these routines in
  157. a commercial, shareware etc. product.
  158.  
  159. Any questions and/or bug fixes, please send email to:
  160.  
  161.         Stephen Chung           stephenc@cunixf.cc.columbia.edu
  162. or        Tim Liddelow            tim@kimba.catt.citri.edu.au
  163.  
  164. If it bounces, then try schung@cogsci.Berkeley.EDU
  165.  
  166. Have fun!
  167.